/**
 * 
 */
package wayic.http;

import java.io.IOException;
import java.io.InputStream;
import java.io.Reader;
import java.io.UnsupportedEncodingException;
import java.net.URL;

/**
 * Interface for exposing behaviour for loading from a URL.
 * 
 * @author Ashesh Nishant
 *
 */
public interface UrlLoader {
	
	/**
	 * Loads an input stream form a URL.
	 * @return. HTTP Header encapsulated of the loaded content.
	 * @throws IOException
	 * The retrun value should be set as metadata for the fetched document.
	 */
	ContentHeader load() throws IOException;
	/**
	 * Loads an input stream form a URL.
	 * The retrun value should be set as metadata for the fetched document.
	 *  
	 * @param header. header passed for loading via conditional get
	 * @return. HTTP Header encapsulated of the loaded content.
	 * @throws IOException
	 */
	ContentHeader load(ContentHeader header) throws IOException;
	/**
	 * @return. User-agent String. 
	 */
	String getUserAgent();
	/**
	 * @return. Boolean to determine if URL-redirects should be followed
	 */
	boolean isRedirectEnabled();
	/**
	 * @return. The URL to be loaded.
	 */
	URL getUrl();
	/**
	 * @return. Timeout value in ms for the connection.
	 */
	int getConnectionTimeout();
	/**
	 * @return
	 * @throws IOException. If load() has not been called prior to this.
	 */
	InputStream getAsInputStream() throws IOException;
	/**
	 * Returns the reader based on default encoding - ISO 8589-1
	 * @return
	 * @throws UnsupportedEncodingException
	 * @throws IOException
	 */
	Reader getAsReader() throws UnsupportedEncodingException, IOException;
	/**
	 * Returns the reader based on provided encoding.
	 * @param encoding
	 * @return
	 * @throws UnsupportedEncodingException
	 * @throws IOException
	 */
	Reader getAsReader(String encoding) throws UnsupportedEncodingException, IOException;
	/**
	 * Returns the string loaded from a URL.
	 * @return
	 * @throws UnsupportedEncodingException
	 * @throws IOException
	 */
	String getAsString() throws UnsupportedEncodingException, IOException;
	/**
	 * Returns the string loaded from a URL based on the given encoding.
	 * @param encoding
	 * @return
	 * @throws UnsupportedEncodingException
	 * @throws IOException
	 */
	String getAsString(String encoding) throws UnsupportedEncodingException, IOException;
	/**
	 * Returns the encoding. 
	 * @return
	 */
	String getEncoding();
	/**
	 * Sets the encoding.
	 * @param encoding
	 */
	void setEncoding(String encoding);
	
	/**
	 * Closes the underlying stream used for loading from a URL. 
	 * Should be called only after an object equivalent has been 
	 * created from the underlying stream. 
	 */
	void close();
}
